Configuring Call Setup Rules

The Call Setup Rules table lets you configure up to 500 for 2-8 GB and 1,000 for 16-64 GB Call Setup Rules.

Call Setup Rules define various script-like sequences that the device runs upon the receipt of an incoming SIP dialog at call setup, before the device routes the call to its destination. You can configure multiple Call Setup Rules and group them under the same Set ID. This lets you run multiple Call Setup Rules for the same call setup dialog.

Call Setup Rules provide flexibility in implementing simple or complex script-like rules that you can use for various functionality:

■

LDAP Queries: The device can be configured to use LDAP to query Microsoft’s Active Directory (AD) server for specific user details needed for routing the call. For example, it could query for the user's office extension number, mobile number, private number, or display name. Call Setup Rules provides full flexibility in AD-lookup configuration to suit just about any deployment requirement:

●

Routing based on query results.

●

Queries based on any AD attribute.

●

Queries based on any attribute value (alphanumeric), including the use of the asterisk (*) wildcard as well as the source number, destination number, redirect number, and SBC SIP messages. For example, the following Call Setup rule queries the attribute "proxyAddresses" for the record value "WOW:" followed by source number: "proxyAddresses=WOW:12345*"

●

Conditional LDAP queries, for example, where the query is based on two attributes (&(telephoneNumber=4064)(company=ABC)).

●

Conditions for checking LDAP query results.

●

Manipulation of call parameters such as source number, destination number, and redirect number and SBC SIP messages, while using LDAP query results.

●

Multiple LDAP queries.

■

Dial Plan Queries: You can use Call Setup Rules to query the Dial Plan table (see Configuring Dial Plans) for a specified key in a specified Dial Plan, to obtain the corresponding Dial Plan tag. Call Setup Rules can also change (modify) the name of the obtained tag. The device can then route the call using an IP-to-IP Routing rule (in the IP-to-IP Routing table) that has a matching tag (source or destination).

You can also use Call Setup Rules for complex routing schemes by using multiple Dial Plan tags. This is typically required when the source or destination of the call needs to be categorized with multiple characteristics. For example, tags can be used to categorize calls by department (source user) within a company, where only certain departments are allowed to place international calls.

■

ENUM Queries: You can use Call Setup Rules to query an ENUM server and to handle responses from the ENUM server. ENUM translates ordinary telephone numbers (E.164 telephone numbers) into Internet addresses (SIP URIs), using the ENUM's DNS NAPTR records. For example, if the device receives an INVITE message whose destination number is in E.164 format, you can configure a Call Setup rule to query the ENUM server for the corresponding URI address, which is then used in the INVITE's Request-URI.

■

HTTP Requests (Queries): You can use Call Setup Rules to query or notify an HTTP/S server, which is configured in the Remote Web Services table (Configuring Remote Web Services). If a response is expected from the server, the query is sent as an HTTP GET or HTTP POST request (configurable). If no response is required from the server (i.e., to notify the server of a specific condition), then an HTTP POST for notifications is sent (configurable).

■

Manipulation: Manipulation (similar to Message Manipulations table) of call parameters (such as source number, destination number, and redirect number) and SBC SIP messages.

■

Conditions for Routing: Routing conditions, for example, if the source number equals a specific value, then use the call routing rule.

■

Tag-based Routing: You can use Call Setup Rules for tag-based routing. The Call Setup Rule Set is assigned to the IP-to-IP Routing rule ('Pre Route Call Setup Rules Set ID' parameter), whose 'Destination Type' parameter is configured to Destination Tag and 'Routing Tag Name' parameter to the name of the tag. When the tag is obtained by the Call Setup Rules (DstTags), the device searches the IP Groups table for a destination IP Group whose 'Tags' parameter matches this tag.

To use Call Setup Rules, you need to assign their Set ID to any of the following configuration entities:

■

IP-to-IP Routing rules, using the 'Call Setup Rules Set ID' or 'Pre Route Call Setup Rules Set ID' parameters (see Configuring SBC IP-to-IP Routing Rules)

■

SIP Interface rules, using the 'Call Setup Rules Set ID' parameter (see Configuring SIP Interfaces)

■

IP Groups, using the 'Call Setup Rules Set ID' parameter (see Configuring IP Groups)

●

If you assign a Call Setup rule to an IP Group, the device runs the Call Setup rule for the classified source IP Group immediately before the routing stage. If you assign the Call Setup rule to a routing rule only, the device first locates a matching routing rule for the incoming call, runs the assigned Call Setup rule, and then routes the call according to the destination of the routing rule.

●

If you want a Call Setup rule to run during the routing stage to determine the destination tag (when the 'Destination Type' parameter is configured to Destination Tag), you must assign the Call Setup rule in the IP-to-IP Routing table using the 'Pre Route Call Setup Rules Set ID' parameter (instead of 'Call Setup Rules Set ID'). For more information of these parameters, see the Configuring SBC IP-to-IP Routing Rules.

For routing, the device uses the selected routing rule for routing the call, depending on whether the condition of the Call Setup rule is met or not, and according to the 'Action Value' parameter's value when the 'Action Type' parameter is configured to Exit. The Exit value is used to discontinue with the Set ID (i.e., doesn't run remaining Call Setup Rules in the Set ID). For example, if you have 10 Call Setup Rules (#1-10) in the Set ID, you can configure rule #5 with Exit so that if its condition is met, it's the last one to run in the Set ID (i.e., rules #6-10 aren't run). Below explains route selection depending on condition and the Exit value:

■

Call Setup Rule's Condition is Met: The device runs the Call Setup rule, and then runs the next rule in the Set ID until the last rule or until a rule whose 'Action Type' parameter is Exit. If there is an "exit" rule, the device's logic is according to the settings of the 'Action Value' parameter:

●

True: The device uses the selected routing rule to route the call.

●

False: The device searches for the next alternative routing rule (if exists).

●

Abort: The device stops (aborts) any further attempts to route the call (i.e., rejects call), even if additional alternative routing rules exist.

■

Call Setup Rule's Condition not Met: The device runs the next Call Setup rule in the Set ID, and when it finishes running all the rules in the Set ID (and no "exit" rule exists), the Set ID ends with a "true" result. However, if there is an "exit" rule (i.e., 'Action Type' parameter is Exit and regardless of the 'Action Value' parameter's value), the device doesn't run the next Call Setup rule, and uses the selected routing rule to route the call.

The optional values True, False, and Abort for the 'Action Value' parameter, used when the 'Action Type' parameter is configured to Exit is applicable only when the Call Setup rule is run from the IP-to-IP Routing table. If run from any other configuration entity (e.g., SIP Interface), the device ignores these values.

The default result of a Call Setup rule is always “true” (True). Therefore, it's important to understand the logic when configuring the ‘Action Type’ field to Exit.

Examples:

■

Example 1: To exit the Set ID with "true" if the LDAP query result is found, and with "false" if the LDAP query result isn't found:

●

Incorrect Configuration: This rule always exits with result as "true":

◆

'Condition': ldap.found exists

◆

'Action Type': Exit

◆

'Action Value': True

●

Correct Configuration:

Single rule:

◆

'Condition': ldap.found !exists

◆

'Action Type': Exit

◆

'Action Value': False

Multiple rules:

◆

'Condition': ldap.found exists

◆

'Action Type': Exit

◆

'Action Value': True

◆

'Condition': <leave empty>

◆

'Action Type': Exit

◆

'Action Value': False

■

Example 2: Assume you've configured the following IP-to-IP Routing rules in the IP-to-IP Routing table:

●

Index #1: 'Alternative Route Options' = Route Row; 'Destination Type' = Destination Tag

●

Index #2: 'Alternative Route Options' = Alternative Route Ignore Inputs; 'Destination Type' = Destination Tag

●

Index #3: 'Alternative Route Options' = Alternative Route Ignore Inputs; 'Destination Type' = Destination Tag

●

Index #4: 'Alternative Route Options' = Alternative Route Ignore Inputs; 'Destination Type' = Destination Tag

●

Index #5: 'Alternative Route Options' = Alternative Route Ignore Inputs; 'Destination Type' = Destination Tag

Assume the device is unable to route the call using rules #1 and #2, and is now processing rule #3. The device handles rule #3 according to the settings of the assigned Call Setup rule:

●

‘Action Type’ is Exit and ‘Action Value’ is Abort: If the rule's Condition is met, the device discontinues its attempt to route the call (doesn't try rules #4 or #5) and aborts call routing (i.e., call fails).

●

‘Action Type’ is Exit and ‘Action Value’ is False: If the rule's Condition is met, the device attempts to route the call using the next matching routing rule (#4).

●

‘Action Type’ is Exit and ‘Action Value’ is True: If the rule's Condition is met, the device sends a SIP INVITE message to the destination, according to routing rule #3. If the device receives a failure response to the INVITE, the device tries the next rule (i.e., #5) to route the call.

●

If the source or destination numbers are manipulated by Call Setup Rules, they revert to their original values if the device moves to the next routing rule.

●

For examples of Call Setup Rules, see Examples of Call Setup Rules.

●

For a detailed description of the syntax for Call Setup Rules, refer to the document SIP Message Manipulation Syntax Reference Guide (click here).

The following procedure describes how to configure Call Setup Rules through the Web interface. You can also configure it through ini file [CallSetupRules] or CLI (configure voip > message call-setup-rules).

➢

To configure a Call Setup rule:

Open the Call Setup Rules table (Setup menu > Signaling & Media tab > SIP Definitions folder > Call Setup Rules).

Click New; the following dialog box appears:

Configure a Call Setup rule according to the parameters described in the table below.

Click Apply, and then save your settings to flash memory.

Call Setup Rules Parameter Descriptions

Parameter

Description

General

'Index'

[Index]

Defines an index number for the new table record.

Note: Each rule must be configured with a unique index.

'Name'

rules-set-name

[RulesSetName]

Defines an arbitrary name to easily identify the row.

The valid value is a string of up to 20 characters.

Note: Configure each row with a unique name.

'Rules Set ID'

rules-set-id

[RulesSetID]

Defines a Set ID for the rule.

You can define the same Set ID for multiple rules to create a group of Call Setup Rules. You can configure up to 32 Set IDs, where each Set ID can include up to 10 rules.

The Set ID is used to assign the Call Setup Rules to configuration entities (e.g., IP-to-IP Routing rules in the IP-to-IP Routing table).

The valid value is 0 to 49 for 2-8 GB and 99 for 16-64 GB. The default is 0.

Note: You can configure up to 25 rules per Set ID.

'Request Type'

request-type

[QueryType]

Defines the type of query.

■

[0] None (default)

■

[1] LDAP = The Call Setup rule runs an LDAP query with an LDAP server. To specify an LDAP server, use the 'Request Target' parameter (see below).

■

[2] Dial Plan = The Call Setup rule runs a query with the Dial Plan. To specify a Dial Plan, use the 'Request Target' parameter (see below).

■

[3] ENUM = The Call Setup rule runs a query with an ENUM (E.164 Number to URI Mapping) server for retrieving a SIP URI address for an E.164 telephone number. The ENUM server’s address is the address configured for the 'Primary DNS' (and optionally, 'Secondary DNS') parameters of the IP Interface (in the IP Interfaces table) that is specified in the ‘Request Target’ parameter (see below). For a configuration example, see Examples of Call Setup Rules.

■

[4] HTTP GET = The Call Setup rule runs an HTTP GET request (query) with an HTTP/S server. To specify an HTTP server, use the 'Request Target' parameter (see below).

■

[5] HTTP POST Query = The Call Setup rule runs an HTTP POST request (query) with an HTTP/S server and expects a response from the server. To specify an HTTP server, use the 'Request Target' parameter (see below).

■

[6] HTTP POST Notification = The Call Setup rule runs an HTTP POST request to notify an HTTP/S server of a specific condition and doesn't expect a response from the server. For example, you can configure a rule to notify the server of a 911 emergency call. To specify an HTTP server, use the 'Request Target' parameter (see below).

'Request Target'

request-target

[QueryTarget]

Defines one of the following, depending on the value configured for the 'Request Type' parameter (above).

■

LDAP: Defines an LDAP server (LDAP Server Group) on which to run an LDAP query for a defined key. To configure LDAP Server Groups, see Configuring LDAP Server Groups.

■

Dial Plan: Defines a Dial Plan (name) in which to search for a defined key. To configure Dial Plans, see Configuring Dial Plans.

■

ENUM: Specifies the ENUM server on which to run the ENUM query. The server is specified by IP Interface name (in the IP Interfaces table). The address of the ENUM server is the address of the 'Primary DNS' (and optionally, 'Secondary DNS') parameters that is configured for the specified IP Interface. If you don’t specify an IP Interface or the specified IP Interface doesn't exist in the IP Interfaces table, the device uses the OAMP IP Interface.

■

HTTP GET, HTTP POST Query, and HTTP POST Notification: Defines the HTTP server to where the device sends the HTTP request. To configure HTTP servers, see Configuring Remote Web Services.

To configure the key, use the 'Request Key' parameter (see below).

'Request Key'

request-key

[AttributesToQuery]

Defines the key to query.

■

For LDAP, the key string is queried on the LDAP server.

■

For Dial Plans, the key string is searched in the specified Dial Plan.

■

For ENUM, the key string is queried on the ENUM server.

■

For HTTP GET and HTTP POST queries, the key string is queried on the HTTP server.

The valid value is a string of up to 100 characters. Combined strings and values can be configured like in the Message Manipulations table, using the '+' operator. Single quotation marks (') can be used for specifying a constant string (e.g., '12345').

You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

Examples:

■

To LDAP query the AD attribute "mobile" that has the value of the destination user part of the incoming call:

'mobile=' + param.call.dst.user

■

To LDAP query the AD attribute "telephoneNumber" that has a redirect number:

'telephoneNumber=' + param.call.redirect + '*'

■

To query a Dial Plan for the source number:

param.call.src.user

■

To query an ENUM server for the URI of the called (destination) number:

param.call.dst.user

■

To send an HTTP POST to notify the HTTP server of call connection status:

'connectionStatus'

Note: The parameter is applicable only if the 'Request Type' parameter is configured to any value other than None.

'Attributes To Get'

attr-to-get

[AttributesToGet]

Defines the Attributes of the queried LDAP record that the device must handle (e.g., retrieve value).

The valid value is a string of up to 255 characters. Up to five attributes can be defined, each separated by a comma (e.g., msRTCSIP-PrivateLine,msRTCSIP-Line,mobile).

Note:

■

The parameter is applicable only if you configure the 'Request Type' parameter to LDAP.

■

The device saves the retrieved attributes' values for future use in other rules until the next LDAP query or until the call is connected. Thus, the device doesn't need to re-query the same attributes.

'Row Role'

row-role

[RowRole]

Defines which condition (as configured in the 'Condition' parameter) must be met for this rule to be run.

■

[0] Use Current Condition = (Default) The Condition configured for this rule must be met to run the configured action.

■

[1] Use Previous Condition = The Condition configured for the rule located directly above this rule in the Call Setup table must be met to run the configured action. This option lets you configure multiple actions for the same Condition.

'Condition'

condition

[Condition]

Defines the condition that must exist for the device to run the configured action of the Call Setup rule.

The valid value is a string of up to 200 characters (case-insensitive). You can also use regular expression (regex).

You can use the built-in syntax editor to help configure the parameter. Click the Editor button located next to the field to open the Editor, and then simply follow the on-screen instructions.

Examples:

■

LDAP:

✔

ldap.attr.mobile exists (if Attribute "mobile" exists in AD)

✔

param.call.dst.user == ldap.attr.msRTCSIP-PrivateLine (if called number is the same as the number in the Attribute "msRTCSIP-PrivateLine")

✔

ldap.found !exists (if LDAP record not found)

✔

ldap.err exists (if LDAP error exists)

■

Dial Plan:

✔

dialplan.found exists (if Dial Plan exists)

✔

dialplan.found !exists (if Dial Plan queried key not found)

✔

dialplan.result=='uk' (if corresponding tag of the searched key is "uk")

■

ENUM:

✔

enum.found exists (if ENUM record of E.164 number exists)

■

HTTP GET or HTTP POST:

●

http.response.status == '200' (if the HTTP server responds with a 200 OK)

Action

'Action Subject'

action-subject

[ActionSubject]

Defines the element (e.g., SIP header, SIP parameter, SIP body, or Dial Plan tag) upon which you want to run the action if the condition (configured in the 'Condition' parameter above) is met.

The valid value is a string of up to 100 characters (case-insensitive). You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

Examples:

■

header.from contains '1234'

■

param.call.dst.user (called number)

■

param.call.src.user (calling number)

■

param.call.src.name (calling name)

■

param.call.redirect (redirect number)

■

param.call.src.host (source host)

■

param.call.dst.host (destination host)

■

srctags (source tag)

■

dsttags (destination tag)

■

referredbytags (tag of transferor, which initiates call transfer)

■

header.content-type (for HTTP POST requests)

'Action Type'

action-type

[ActionType]

Defines the type of action to run.

■

[-1] None = No action is run. This option is typically used for HTTP POST requests that are used for notifying the HTTP server (e.g., when the 'Request Type' parameter is configured to HTTP POST Notification). If you configure the parameter to this option and it is the last rule in the table, the device runs the rule and then exits the table. If it is not the last rule, the device runs the rule and then checks the next rule.

■

[0] Add = (Default) Adds a new message header, parameter, or body elements.

■

[1] Remove = Removes a message header, parameter, or body elements.

■

[2] Modify = Sets the element to the new value (all element types).

■

[3] Add Prefix = Adds a value at the beginning of the string (string element only).

■

[4] Add Suffix = Adds a value at the end of the string (string element only).

■

[5] Remove Suffix = Removes a value from the end of the string (string element only).

■

[6] Remove Prefix = Removes a value from the beginning of the string (string element only).

■

[20] Run Rules Set = Runs a different Rule Set ID, which is specified in the 'Action Value' parameter (see below)

■

[21] Exit = Stops running the remaining rules in the Rule Set ID and returns a result ("true", "false", or "abort").

'Action Value'

action-value

[ActionValue]

Defines a value for the action.

The valid value is a string of up to 300 characters (case-insensitive). You can use the built-in syntax editor to help configure the field. Click the Editor button located next to the field to open the Editor, and then simply follow the on-screen instructions.

Examples:

■

'+9723976'+ldap.attr.alternateNumber

■

'9764000'

■

ldap.attr.displayName

■

enum.result.url

■

srctags

■

http.response.body

■

application/x-www-form-urlencoded (for HTTP Content-Type header in HTTP requests)

■

True

■

False

■

Abort

Note: The values True, False, and Abort are applicable only when the 'Action Type' parameter is configured to Exit and only when the Call Setup rule is run from the IP-to-IP Routing table. For a description of these values, see the first part of this section.